//
// DepRepo
//
// Copyright (C) jextra.net.
//
//  This file is part of the net.jextra.dep Library.
//
//  The net.jextra.dep Library is free software; you can redistribute it and/or
//  modify it under the terms of the GNU Lesser General Public
//  License as published by the Free Software Foundation; either
//  version 2.1 of the License, or (at your option) any later version.
//
//  The net.jextra.dep Library is distributed in the hope that it will be useful,
//  but WITHOUT ANY WARRANTY; without even the implied warranty of
//  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
//  Lesser General Public License for more details.
//
//  You should have received a copy of the GNU Lesser General Public
//  License along with the net.jextra.dep Library; if not, write to the Free
//  Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
//  02111-1307 USA.
//

package net.jextra.dep.repo;

import java.io.*;
import java.util.*;

public interface DepRepo
{
    /**
     * General purpose means to initialize a DepRepo. The params is most likely specified in
     * an XML file.
     */
    void init( DepRepoParam params )
        throws Exception;

    /**
     * This should be a name that uniquely defines a repo which will be different than another
     * repo that does not "point" to the same place.
     */
    String getName()
        throws Exception;

    /**
     * This is the amount of time to attempt to access the repo (In milliseconds).
     */
    int getTimeout()
        throws Exception;

    /**
     * Get list of all versions in the repo from 'latest version' to 'earliest version'.
     */
    List<DepRepoVersion> getVersions( String componentName )
        throws Exception;

    /**
     * Given a pattern to a directory, return 'latest' sub-directory within it.
     */
    String getLatestVersionNumber( String componentName )
        throws Exception;

    /**
     * Used by auto-generating version numbers to get next version number for the given component.
     */
    String getNextVersionNumber( String componentName )
        throws Exception;

    /**
     * Get list of {@link DepRepoFile}'s (files and sub-dirs) within a given path.
     */
    List<DepRepoFile> getFileEntries( String componentName, String versionNumber, String path )
        throws Exception;

    /**
     * Get a single entry from the repo.
     */
    DepRepoFile getFileEntry( String componentName, String versionNumber, String path )
        throws Exception;

    /**
     * Get a URL that corresponds to the given path.
     */
    InputStream getFileEntryInputStream( String componentName, String versionNumber, String path )
        throws Exception;

    String getComponentDisplayName( String componentName, String versionNumber )
        throws Exception;

    /**
     * <p>
     * Save a file to the given componentName/versionNumber/path. The path should include the name of the file
     * that will be created that may also be prefixed by a relative path.
     * </p><p>
     * If the file already exists, it will be overridden.
     * </p>
     */
    void uploadFile( String componentName, String versionNumber, String path, File file )
        throws Exception;
}
